%==========================================================================
%=  This file is part of the Sound Restoration Project
%=  (c) Copyright Industrial Mathematics Institute
%=                University of South Carolina, Department of Mathematics
%=  ALL RIGHTS RESERVED
%=
%=  Author: Borislav Karaivanov
%==========================================================================

%==========================================================================
% List of the files on which this procedure depends:
%
% readImageFile.m
% readdpx.m
% Image processing toolbox
%
%==========================================================================

%==========================================================================
% The function "readImageByIndex" reads in an image file with specified
% prefix, index, end extension. The file can be either a dpx or a pgm file.
% INPUT: "fileInd" specifies the index of the file to be read.
% "inFileNamePrefix" is a string specifying the prefix (including a full
% directory path) in the name of the image file to be read.
% "indFieldLength" is an optional parameter specifying the number of digits
% used to specify the index of a image in its file name. Image indices are
% specified with leading zeros. For example, if the index field length is
% 6, then the index of image 241 is specified as 000241 in its file name.
% "imageFileExt" is an optional string specifying the extension of the
% image file to be read. Admissible extensions are 'dpx' and 'pgm' with the
% former used by default.
% "doConvertToGray" is an optional logical parameter specifying whether or
% not a grayscale version of the read image is to be returned.
% OUTPUT: "imageArr" returns a 2D image array holding the read image.
% "bitDepth" returns the number of bits used to encode each pixel value.
%==========================================================================
function [imageArr, bitDepth] = readImageByIndex(fileInd, inFileNamePrefix, ...
    indFieldLength, imageFileExt, doConvertToGray)

if (nargin < 3)
    indFieldLength = 6;
end
if (nargin < 4)
    imageFileExt = 'dpx';
end
if (nargin < 5)
    doConvertToGray = false;
end

% Generate the file name.
indStr = num2str(fileInd, ['%0' num2str(indFieldLength) 'd']);
fileName = [inFileNamePrefix indStr '.' imageFileExt];

% Assert that the image file exists.
assert((exist(fileName, 'file') == 2), ...
    'SoundRestoration:readImageByIndex:InFileInexisting', ...
    ['The image file %s can not be found.\n' ...
    'A non-empty string specifying a full directory path to an existing file is needed.'], fileName);

% Read in the image file.
[imageArr, bitDepth] = readImageFile(fileName);

% Convert to a grayscale image in case the read pixels have three
% components (like RGB).
if ( (doConvertToGray == true)&&(ndims(imageArr) == 3) )
    imageArr = rgb2gray(imageArr);
end
    
% % Store the read image. Keep only one copy of the image (there might be
% % three identical copies stored in a 3D array meant to accommodate RGB
% % image data).
% imageArr = double(imageArr(:, :, 1));
    
return;
% end of the function "readImageByIndex"
